Creating and Drawing Lines (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 2 - Geometric Shapes / Using Geometric Shapes

Creating and Drawing Lines
You can draw lines and create line shapes with QuickDraw GX in much the same way as you draw points and create point shapes. Typically, you first define a line geometry, which is encapsulated in a gxLine structure:
struct gxLine {
   struct gxPoint first;
   struct gxPoint last;
};
Once you've defined a line geometry, you can draw the corresponding line without creating a line shape by using the GXDrawLine function, as shown in Listing 2-6.
Listing 2-6 Drawing a line without creating a line shape
void DrawASingleLine(void)
{
   static gxLine aLineGeometry = {{ff(50), ff(50)},
                                  {ff(150), ff(150)}}; 
   
   GXDrawLine(&aLineGeometry);
}
This sample function defines a line geometry, using the ff macro (which is an alias for the GXIntToFixed macro) to convert integer constants to fixed-point coordinate values. It then uses the GXDrawLine function to draw the line. The GXDrawLine function uses the style, ink, and transform information from the default line shape when drawing the line. The result is shown in Figure 2-19.
Figure 2-19 A line

As with the point shape in Figure 2-17, the line shape in Figure 2-19 is infinitely thin, but is drawn one-pixel wide--a hairline--because the default value of the pen width property of the style object is 0, which indicates that QuickDraw GX should draw the line at the thinnest perceivable resolution.
Another method of drawing a line is to encapsulate the line geometry in a line shape and then use the GXDrawShape function to draw the line. This method allows you to specify different style, ink, and transform information for the line. The sample function in Listing 2-7 uses this method: it creates a line shape using the GXNewLine function and then draws the line using the GXDrawShape function.
Listing 2-7 Creating a line shape with the GXNewLine function
void CreateLineShape(void)
{
   gxShape     aLineShape;
   
   static gxLine aLineGeometry = {ff(50), ff(50),
                                  ff(150), ff(150)}; 
   
   
   aLineShape = GXNewLine(&aLineGeometry);
   
   GXDrawShape(aLineShape);
   
   GXDisposeShape(aLineShape);
}
You can also use the GXNewShape or GXNewShapeVector functions to create a line shape. For example, to create the same line shape using the GXNewShape function, you could replace this line of code in the previous example:
aLineShape = GXNewLine(&aLineGeometry);
with these lines of code:
aLineShape = GXNewShape(gxLineType);
GXSetLine(aLineShape, &aLineGeometry);
In either case, the line shape would be the same, and would appear as shown in
Figure 2-19.
The sample function in Listing 2-8 shows how to use the GXSetLine function to change the geometry of an existing line shape.
Listing 2-8 Drawing two parallel lines
void DrawParallelLines(void)
{
   gxShape      aLineShape;
   
   static gxLine aLineGeometry = {ff(50), ff(50),
                                 ff(57), ff(100)}; 

   static gxLine anotherLineGeometry = {ff(60), ff(50),
                                       ff(67), ff(100)}; 
   
   
   aLineShape = GXNewShape(gxLineType);
   GXSetLine(aLineShape, &aLineGeometry);

   GXDrawShape(aLineShape);
   
   GXSetLine(aLineShape, &anotherLineGeometry);
   
   GXDrawShape(aLineShape);
   
   GXDisposeShape(aLineShape);
}
This sample function creates and draws a line shape, changes its geometry, and then draws it again. The results are shown in Figure 2-20.
Figure 2-20 Parallel lines

As with any geometric shape, you can specify fractional values for a line shape's geometric points. Although specifying a fractional part does not move the start pixel or the end pixel of line (unless rounding occurs), it can affect how the line is drawn. When QuickDraw GX draws a line with fractional endpoint coordinates, rather than integer endpoint coordinates, it may choose different pixels to represent the line, even if the endpoints remain on the same pixels in both cases. By choosing a different "stair step" pattern to represent the line, QuickDraw GX can give the illusion of very slight changes in line angles. As an example, if in the previous example you replace the second definition:
static gxLine anotherLineGeometry = {ff(60), ff(50),
                                     ff(67), ff(100)};
with a slightly modified version:
static gxLine anotherLineGeometry = {fl(59.6), ff(50),
                                     fl(67.4), ff(100)}; 
QuickDraw GX chooses different pixels to represent the second line, giving the appearance of a slightly different angle, as shown in Figure 2-21.
Figure 2-21 Nearly parallel lines

For more information about line shapes, see "Line Shapes" on page 2-17 and "The Line Structure" on page 2-105.
For information about the functions you can use to create and draw lines, see the description of the GXNewLine function on page 2-112 and the GXDrawLine function on page 2-158.